
		      Doors OS version 0.7 Beta
			  by the Doors Team
			     for TI 89

			Copyright  (C) 1998 
			   Xavier VASSOR
			 Cedric COUFFIGNAL			
			All rights reserved.

----------------------------------------------------------------------
			TABLE OF CONTENTS
----------------------------------------------------------------------

I)   Introduction
II)  Installing Doors
III) Programming for Doors
IV)  Planned Features
V)   How to contact us
VI)  History

----------------------------------------------------------------------
			I) Introduction
----------------------------------------------------------------------

	Doors OS is a kernel which will allow execution of high featured
assembly programs on your TI 89.
	It mainly features:
	- Libraries
	- Anti Crash system
	- BSS

	The actual version doesn't handle the Anti Crash but it should
be done very soon.

	There will also be included some libraries which will allow to:
- Use the variables and folder system of the TI 89
- Use graphical functions in 2, 4 or 7 grayshades, to make beautiful games.
- Use password functions.

----------------------------------------------------------------------
			II) Installing and using Doors
----------------------------------------------------------------------

Requirements
------------

	To install Doors OS you need:
	- A Graph-Link (TM) cable and the TI89 GraphLink software (you
can download it at http://www.ti.com/calc)
	- A TI 89 :)

Installation
------------

	First unzip all files contained in DoorsOS.zip in the folder of
your choice. (You can use WinZip or Pkunzip)

	Then use the Graph-Link to transfer the programe named doorsos.89z
to your calculator.

	Run doorsos from your calculator (type doorsos at the home screen
and press Enter). This will install the Doors kernel on the calculator.
	You can delete the doorsos file from your calculator after that

	Now you can execute any assembly program: just execute it like
any other program on the TI89

----------------------------------------------------------------------
			III) Programming for Doors
----------------------------------------------------------------------

	First of all, there are 2 different programs: programs and libraries
	The only differences between them is that programs have:
		- A comment
		- A main entry point
	That's all, so programs AND libraries can export functions, have
BSS blocks, import functions from others programs and libraries.

How to compile a program or a library
-------------------------------------

	Suppose that you unzipped Doors in the folder C:\Doors
	The first thing to do is to add this lines in autoexec.bat:

	SET DOORS89=C:\DOORS
	SET PATH=%PATH%;%DOORS89%\BIN

	Now you can compile a program or a library from the Dos command line:

	C:\DOORS>Doors <prog>

	With prog the name of the .asm file without its extension.


How to Export functions
-----------------------
At the beginning of your program or library, you can export functions
with a 'xdef	prog@XXXX' line, XXXX being an hexadecimal number. It
indicates the index of the exported function.

But programs and libraries should have their include file whenever they
export functions.
For example, for a library called "graph", suppose that graph@0000 clears
the screen. Then in "graph.h" there should be:

graph::clearscr	equ	graph@0000

Then if a program or a library wants to use this function it will just
have to have	
	include "graph.h" at the beginning, and when it wants to clear
the screen, it writes:
	jsr	graph::clearscr


Program example:
----------------
Let's call it 'test'.

	include	"doorsos.h"	;aliases for ROM functions and RAM adresses
	include	"lib.h"		;allows the use of functions exported from 'lib'

	xdef	_main	;tells that there is an entry point, so we know this is a program
	xdef	_comment ;do this only of you want a comment 
	xdef	test@0000	;first exported function
	...
_main:			;label of the beginning code of you program
	...
test@0000:		;first exported function
	...
	rts		;return from function
	...
	jsr	lib::function	;calls a function in 'lib'
	rts	; return from program
	...
_comment	dc.b	"Program version 2.0",0

	BSS	;tells there is a BSS block
;define here all vars you want to be in the BSS block.
;they are not initialised
buffer	ds.b	50
	...

	end	;tells the assembler that the file is finished.

Note: You don't always need to define comment, or to use a BSS block.

Library example:
----------------

Let's call this library 'lib'.

	include	"doorsos.h"	;aliases for ROM functions and RAM adresses
	xdef	_library	;tells that this is a library. 
	xdef	lib@0000
	xdef	lib@0001
	...
	xdef	lib@XXXX

lib@0000:
	...
	rts	;exits

lib@0001:
	...
	rts	;exits

	...

	end	;the file is finished.

ROM functions and RAM adresses: (aliased in "doorsos.h")
-------------------------------

	We have currently no time to document ROM functions, but here is
info about RAM adresses we have found. Of course when TI will have given
all informations, it will be a lot better.

LCD_MEM		equ	$4c00	;the adress of the screen
doorsos::main_lcd equ LCD_MEM
doorsos::globals equ $4c00

The screen is a 160*100 black and white LCD screen.
The video memory has the same structure than the TI 92.
So: one line on the screen is 20 bytes long, but one line in the video
memory is 30 bytes long (only the 20 first bytes are used)


doorsos::kb_globals equ $759E
doorsos::kb_vars equ doorsos::kb_globals

keyboard variables:
for example doorsos::kb_vars+$1C is the key flag. When not null, the code
of the key pressed is the word at doorsos::kb_vars+$1E

APD_INIT equ LCD_MEM+$F10	;initial value of the APD
APD_TIMER equ LCD_MEM+$F14	;the APD timer
APD_FLAG equ LCD_MEM+$F42	;the APD flag

doorsos::Heap      equ     $758E ;pointer to the Handle Table
doorsos::TopHeap   equ     $7582 ;pointer to a long word which indicates the adress of the top of the Heap
doorsos::MaxHandles equ    $7578 ;number of handles that the Handle Table can contain.

doorsos::HomeScreenEntryHandle	equ	$7708; pointer to the handle of the Home Screen Entry


doorsos::DEREF     macro   ; Dn,An
	lsl.w	#2,\1
        move.l  doorsos::Heap,\2
	move.l	0(\2,\1.w),\2
		endm
This macro gives you in \2 the adress associated with the handle \1

----------------------------------------------------------------------
			IV) Planned Features
----------------------------------------------------------------------

Many things will be added in a near future:
	- The "Anti Crash" system.
	- We will include our gfx, file, and common function libraries
	- TSR programs management
	- Improve docs and sample programs quickly
	- Anything that you want :)

An important thing: we will try to keep the same code format.
What's more, when TI will have released infos, much more ROM calls will
be accessible.

----------------------------------------------------------------------
			V) How to contact us
----------------------------------------------------------------------

You can write us at: <xvassor@mail.dotcom.fr>

But if you have a question about programmation, you would better write
to the Assembly-89 mailing list <assembly-89@lists.ticalc.org>.

Please report any bug you find on Doors, so that we can correct it very
quickly !!
